/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.net.smtp;
import java.io.IOException;
import java.io.Writer;
import java.net.InetAddress;
import org.apache.commons.net.io.DotTerminatedMessageWriter;
/***
* SMTPClient encapsulates all the functionality necessary to send files
* through an SMTP server. This class takes care of all
* low level details of interacting with an SMTP server and provides
* a convenient higher level interface. As with all classes derived
* from {@link org.apache.commons.net.SocketClient},
* you must first connect to the server with
* {@link org.apache.commons.net.SocketClient#connect connect }
* before doing anything, and finally
* {@link org.apache.commons.net.SocketClient#disconnect disconnect }
* after you're completely finished interacting with the server.
* Then you need to check the SMTP reply code to see if the connection
* was successful. For example:
* <pre>
* try {
* int reply;
* client.connect("mail.foobar.com");
* System.out.print(client.getReplyString());
*
* // After connection attempt, you should check the reply code to verify
* // success.
* reply = client.getReplyCode();
*
* if(!SMTPReply.isPositiveCompletion(reply)) {
* client.disconnect();
* System.err.println("SMTP server refused connection.");
* System.exit(1);
* }
*
* // Do useful stuff here.
* ...
* } catch(IOException e) {
* if(client.isConnected()) {
* try {
* client.disconnect();
* } catch(IOException f) {
* // do nothing
* }
* }
* System.err.println("Could not connect to server.");
* e.printStackTrace();
* System.exit(1);
* }
* </pre>
* <p>
* Immediately after connecting is the only real time you need to check the
* reply code (because connect is of type void). The convention for all the
* SMTP command methods in SMTPClient is such that they either return a
* boolean value or some other value.
* The boolean methods return true on a successful completion reply from
* the SMTP server and false on a reply resulting in an error condition or
* failure. The methods returning a value other than boolean return a value
* containing the higher level data produced by the SMTP command, or null if a
* reply resulted in an error condition or failure. If you want to access
* the exact SMTP reply code causing a success or failure, you must call
* {@link org.apache.commons.net.smtp.SMTP#getReplyCode getReplyCode } after
* a success or failure.
* <p>
* You should keep in mind that the SMTP server may choose to prematurely
* close a connection for various reasons. The SMTPClient class will detect a
* premature SMTP server connection closing when it receives a
* {@link org.apache.commons.net.smtp.SMTPReply#SERVICE_NOT_AVAILABLE SMTPReply.SERVICE_NOT_AVAILABLE }
* response to a command.
* When that occurs, the method encountering that reply will throw
* an {@link org.apache.commons.net.smtp.SMTPConnectionClosedException}
* .
* <code>SMTPConectionClosedException</code>
* is a subclass of <code> IOException </code> and therefore need not be
* caught separately, but if you are going to catch it separately, its
* catch block must appear before the more general <code> IOException </code>
* catch block. When you encounter an
* {@link org.apache.commons.net.smtp.SMTPConnectionClosedException}
* , you must disconnect the connection with
* {@link #disconnect disconnect() } to properly clean up the
* system resources used by SMTPClient. Before disconnecting, you may check
* the last reply code and text with
* {@link org.apache.commons.net.smtp.SMTP#getReplyCode getReplyCode },
* {@link org.apache.commons.net.smtp.SMTP#getReplyString getReplyString },
* and
* {@link org.apache.commons.net.smtp.SMTP#getReplyStrings getReplyStrings}.
* <p>
* Rather than list it separately for each method, we mention here that
* every method communicating with the server and throwing an IOException
* can also throw a
* {@link org.apache.commons.net.MalformedServerReplyException}
* , which is a subclass
* of IOException. A MalformedServerReplyException will be thrown when
* the reply received from the server deviates enough from the protocol
* specification that it cannot be interpreted in a useful manner despite
* attempts to be as lenient as possible.
* <p>
* <p>
* @author Daniel F. Savarese
* @see SMTP
* @see SimpleSMTPHeader
* @see RelayPath
* @see SMTPConnectionClosedException
* @see org.apache.commons.net.MalformedServerReplyException
***/
public class SMTPClient extends SMTP
{
/**
* Default SMTPClient constructor. Creates a new SMTPClient instance.
*/
public SMTPClient() { }
/**
* Overloaded constructor that takes an encoding specification
* @param encoding The encoding to use
* @since 2.0
*/
public SMTPClient(String encoding) {
super(encoding);
}
/***
* At least one SMTPClient method ({@link #sendMessageData sendMessageData })
* does not complete the entire sequence of SMTP commands to complete a
* transaction. These types of commands require some action by the
* programmer after the reception of a positive intermediate command.
* After the programmer's code completes its actions, it must call this
* method to receive the completion reply from the server and verify the
* success of the entire transaction.
* <p>
* For example,
* <pre>
* writer = client.sendMessage();
* if(writer == null) // failure
* return false;
* header =
* new SimpleSMTPHeader("foobar@foo.com", "foo@foobar.com", "Re: Foo");
* writer.write(header.toString());
* writer.write("This is just a test");
* writer.close();
* if(!client.completePendingCommand()) // failure
* return false;
* </pre>
* <p>
* @return True if successfully completed, false if not.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public boolean completePendingCommand() throws IOException
{
return SMTPReply.isPositiveCompletion(getReply());
}
/***
* Login to the SMTP server by sending the HELO command with the
* given hostname as an argument. Before performing any mail commands,
* you must first login.
* <p>
* @param hostname The hostname with which to greet the SMTP server.
* @return True if successfully completed, false if not.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public boolean login(String hostname) throws IOException
{
return SMTPReply.isPositiveCompletion(helo(hostname));
}
/***
* Login to the SMTP server by sending the HELO command with the
* client hostname as an argument. Before performing any mail commands,
* you must first login.
* <p>
* @return True if successfully completed, false if not.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public boolean login() throws IOException
{
String name;
InetAddress host;
host = getLocalAddress();
name = host.getHostName();
if (name == null)
return false;
return SMTPReply.isPositiveCompletion(helo(name));
}
/***
* Set the sender of a message using the SMTP MAIL command, specifying
* a reverse relay path. The sender must be set first before any
* recipients may be specified, otherwise the mail server will reject
* your commands.
* <p>
* @param path The reverse relay path pointing back to the sender.
* @return True if successfully completed, false if not.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public boolean setSender(RelayPath path) throws IOException
{
return SMTPReply.isPositiveCompletion(mail(path.toString()));
}
/***
* Set the sender of a message using the SMTP MAIL command, specifying
* the sender's email address. The sender must be set first before any
* recipients may be specified, otherwise the mail server will reject
* your commands.
* <p>
* @param address The sender's email address.
* @return True if successfully completed, false if not.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public boolean setSender(String address) throws IOException
{
return SMTPReply.isPositiveCompletion(mail("<" + address + ">"));
}
/***
* Add a recipient for a message using the SMTP RCPT command, specifying
* a forward relay path. The sender must be set first before any
* recipients may be specified, otherwise the mail server will reject
* your commands.
* <p>
* @param path The forward relay path pointing to the recipient.
* @return True if successfully completed, false if not.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public boolean addRecipient(RelayPath path) throws IOException
{
return SMTPReply.isPositiveCompletion(rcpt(path.toString()));
}
/***
* Add a recipient for a message using the SMTP RCPT command, the
* recipient's email address. The sender must be set first before any
* recipients may be specified, otherwise the mail server will reject
* your commands.
* <p>
* @param address The recipient's email address.
* @return True if successfully completed, false if not.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public boolean addRecipient(String address) throws IOException
{
return SMTPReply.isPositiveCompletion(rcpt("<" + address + ">"));
}
/***
* Send the SMTP DATA command in preparation to send an email message.
* This method returns a DotTerminatedMessageWriter instance to which
* the message can be written. Null is returned if the DATA command
* fails.
* <p>
* You must not issue any commands to the SMTP server (i.e., call any
* (other methods) until you finish writing to the returned Writer
* instance and close it. The SMTP protocol uses the same stream for
* issuing commands as it does for returning results. Therefore the
* returned Writer actually writes directly to the SMTP connection.
* After you close the writer, you can execute new commands. If you
* do not follow these requirements your program will not work properly.
* <p>
* You can use the provided
* {@link org.apache.commons.net.smtp.SimpleSMTPHeader}
* class to construct a bare minimum header.
* To construct more complicated headers you should
* refer to RFC 822. When the Java Mail API is finalized, you will be
* able to use it to compose fully compliant Internet text messages.
* The DotTerminatedMessageWriter takes care of doubling line-leading
* dots and ending the message with a single dot upon closing, so all
* you have to worry about is writing the header and the message.
* <p>
* Upon closing the returned Writer, you need to call
* {@link #completePendingCommand completePendingCommand() }
* to finalize the transaction and verify its success or failure from
* the server reply.
* <p>
* @return A DotTerminatedMessageWriter to which the message (including
* header) can be written. Returns null if the command fails.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public Writer sendMessageData() throws IOException
{
if (!SMTPReply.isPositiveIntermediate(data()))
return null;
return new DotTerminatedMessageWriter(_writer);
}
/***
* A convenience method for sending short messages. This method fetches
* the Writer returned by {@link #sendMessageData sendMessageData() }
* and writes the specified String to it. After writing the message,
* this method calls {@link #completePendingCommand completePendingCommand() }
* to finalize the transaction and returns
* its success or failure.
* <p>
* @param message The short email message to send.
* @return True if successfully completed, false if not.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public boolean sendShortMessageData(String message) throws IOException
{
Writer writer;
writer = sendMessageData();
if (writer == null)
return false;
writer.write(message);
writer.close();
return completePendingCommand();
}
/***
* A convenience method for a sending short email without having to
* explicitly set the sender and recipient(s). This method
* sets the sender and recipient using
* {@link #setSender setSender } and
* {@link #addRecipient addRecipient }, and then sends the
* message using {@link #sendShortMessageData sendShortMessageData }.
* <p>
* @param sender The email address of the sender.
* @param recipient The email address of the recipient.
* @param message The short email message to send.
* @return True if successfully completed, false if not.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public boolean sendSimpleMessage(String sender, String recipient,
String message)
throws IOException
{
if (!setSender(sender))
return false;
if (!addRecipient(recipient))
return false;
return sendShortMessageData(message);
}
/***
* A convenience method for a sending short email without having to
* explicitly set the sender and recipient(s). This method
* sets the sender and recipients using
* {@link #setSender setSender } and
* {@link #addRecipient addRecipient }, and then sends the
* message using {@link #sendShortMessageData sendShortMessageData }.
* <p>
* @param sender The email address of the sender.
* @param recipients An array of recipient email addresses.
* @param message The short email message to send.
* @return True if successfully completed, false if not.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public boolean sendSimpleMessage(String sender, String[] recipients,
String message)
throws IOException
{
boolean oneSuccess = false;
int count;
if (!setSender(sender))
return false;
for (count = 0; count < recipients.length; count++)
{
if (addRecipient(recipients[count]))
oneSuccess = true;
}
if (!oneSuccess)
return false;
return sendShortMessageData(message);
}
/***
* Logout of the SMTP server by sending the QUIT command.
* <p>
* @return True if successfully completed, false if not.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public boolean logout() throws IOException
{
return SMTPReply.isPositiveCompletion(quit());
}
/***
* Aborts the current mail transaction, resetting all server stored
* sender, recipient, and mail data, cleaing all buffers and tables.
* <p>
* @return True if successfully completed, false if not.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public boolean reset() throws IOException
{
return SMTPReply.isPositiveCompletion(rset());
}
/***
* Verify that a username or email address is valid, i.e., that mail
* can be delivered to that mailbox on the server.
* <p>
* @param username The username or email address to validate.
* @return True if the username is valid, false if not.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public boolean verify(String username) throws IOException
{
int result;
result = vrfy(username);
return (result == SMTPReply.ACTION_OK ||
result == SMTPReply.USER_NOT_LOCAL_WILL_FORWARD);
}
/***
* Fetches the system help information from the server and returns the
* full string.
* <p>
* @return The system help string obtained from the server. null if the
* information could not be obtained.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public String listHelp() throws IOException
{
if (SMTPReply.isPositiveCompletion(help()))
return getReplyString();
return null;
}
/***
* Fetches the help information for a given command from the server and
* returns the full string.
* <p>
* @param command The command on which to ask for help.
* @return The command help string obtained from the server. null if the
* information could not be obtained.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public String listHelp(String command) throws IOException
{
if (SMTPReply.isPositiveCompletion(help(command)))
return getReplyString();
return null;
}
/***
* Sends a NOOP command to the SMTP server. This is useful for preventing
* server timeouts.
* <p>
* @return True if successfully completed, false if not.
* @exception SMTPConnectionClosedException
* If the SMTP server prematurely closes the connection as a result
* of the client being idle or some other reason causing the server
* to send SMTP reply code 421. This exception may be caught either
* as an IOException or independently as itself.
* @exception IOException If an I/O error occurs while either sending a
* command to the server or receiving a reply from the server.
***/
public boolean sendNoOp() throws IOException
{
return SMTPReply.isPositiveCompletion(noop());
}
}